home *** CD-ROM | disk | FTP | other *** search
/ BCI NET / BCI NET Dec 94.iso / archives / programming / blitzbasic / riblitzlibs.lha / riblitzlibs / fns / FNS_Library.DOC < prev    next >
Encoding:
Text File  |  2002-02-02  |  12.3 KB  |  328 lines
  1. FNS Library v0.992
  2. ==================
  3.  
  4. By Stephen McNamara
  5. (c)1994 Reflective Images
  6.  
  7. This Blitz2 library prints proportional fonts in either Amiga or Blitz
  8. mode.  It uses my own (rather primitive) font file format, details of which
  9. can be found at the end of this text file.  Fonts can be upto 64 pixels
  10. wide and any height (although the font editor is limited to 64 pixels at
  11. the present moment).  Fonts can be output in upto 256 colours (AGA!) and
  12. in the following ways: bold, centred, underlined, right-aligned or just
  13. standard left-aligned.
  14.  
  15. Note: a default font (PERSONAL.8) is built into this library and can be
  16. used by simply using font number 0.  You do not have to install this font,
  17. it is automatically available for your use.  A second point is to make
  18. is that the library is set up with a clipping rectangle of 0,0 to 0,0.
  19. Thus you have to use either FNSClip, FNSClipOutput or FNSOutput (with the
  20. optional clip parameter) to set the clipping rectangle before you try to
  21. print anything.
  22.  
  23. Please feel free to critisise (or praise!) this library, send me anything
  24. you want to say about it at:
  25.  
  26.     SIS3149@SISVAX.PORT.AC.UK (?)
  27.  
  28. Or send me anything you've written........
  29.  
  30.  
  31.  
  32. Command list:
  33.         a.b=InstallFNS(font#,address)
  34.         RemoveFNS font#
  35.         FNSPrint font#,x,y,a$/string_address[,prefs,colour]
  36.         FNSOutput bitmap#[,clip_update]
  37.         FNSInk colour#
  38.         FNSPrefs preferences[,colour#]
  39.         a.w=FNSHeight(font#)
  40.         a.w=FNSUnderline(font#)
  41.         a.w=FNSWidth(font#)
  42.         FNSClip x1,y1,x2,y2
  43.         FNSClipOutput
  44.         FNSOrigin [x,y]
  45.         a.w=FNSLength(font#,a$/string_address[,prefs])
  46.         a.q=FNSVersion
  47.         FNSSetTab tab_width
  48.         suc=FNSLoad (filename$,font#)
  49.         FNSUnLoad font#
  50.         address.l=FNSSlot
  51.  
  52. Note: All return values will be words except when using InstallFNS and
  53.       FNSVersion.
  54.  
  55.  
  56. Function: InstallFNS
  57. ------------------------------------------------------------------------
  58. Modes : Amiga/Blitz
  59. Syntax: font_num.b=InstallFNS(font_num.b,address.l)
  60.  
  61.   This is used to install a font so that it is available for use by
  62.   the output routines.  Font_num should be a number >=0 and <=15,
  63.   address should be the address in memory of the FNS font file.
  64.   This function will check that the address given does contain a FNS
  65.   font (it will look for the header 'FNS.'), if it cannot find the font
  66.   or something else goes wrong it will return a 0 to you, otherwise it
  67.   will return the number the font was installed as.
  68.  
  69.   Note: The font number you give is automatically ANDED with $F when you
  70.         call this function, thus if you supply a number greater that 15
  71.         you could actually overwrite a previously installed font.
  72.  
  73.   See: RemoveFNS
  74.  
  75. Statement: RemoveFNS
  76. ------------------------------------------------------------------------
  77. Modes : Amiga/Blitz
  78. Syntax: RemoveFNS font#
  79.  
  80.   This command simply removes an installed font from the list of font
  81.   held internally by the FNS routines.  There is no real need to remove
  82.   fonts as installing fonts takes up no memory, except of course the 
  83.   actual font data.  You do not need to remove FNS fonts before ending a
  84.   program.
  85.  
  86.   See: InstallFNS
  87.  
  88. Statement: FNSPrint
  89. ------------------------------------------------------------------------
  90. Modes : Amiga/Blitz
  91. Syntax: FNSPrint font_num.b,x.w,y.w,a$/string_address[,preferences,colour]
  92.  
  93.   This command prints the string a$ in an FNS font at the position X,Y.
  94.   Font_num is the number of a previously installed FNS font, the output
  95.   of this command is sent to the current FNS bitmap (see FNSOutput). You
  96.   can setting a drawing rectangle on the currently used bitmap to limit
  97.   the output of the font - see FNSClip for more info.
  98.  
  99.   Instead of a string, though, you can give the address of a null
  100.   terminated string in memory.  Also, you can change the colour that text 
  101.   is being output in in the current string by putting the character ASCII 1
  102.   followed by a byte value from 0-255 specifying the colour to change to.
  103.   The printing routine also lets you use a TAB character (ASCii 9) in your
  104.   string.  You should note, though, that this character is not allocated
  105.   any space when it comes to calculating the length of a string (centring
  106.   text and right aligning).  See FNSSetTab for how to set your own TAB
  107.   spacing value.
  108.  
  109.   The optional parameters are for controlling how the text is output.
  110.   They automatically overide the default setting but are not permanent,
  111.   i.e. the default output style and colour are restored after the line
  112.   has been output.  Use FNSInk and FNSPrefs to set the default font
  113.   output mode.
  114.  
  115.   See: FNSOuput, FNSInk, FNSPrefs, FNSOrigin and FNSClip.
  116.  
  117. Statement: FNSOutput
  118. ------------------------------------------------------------------------
  119. Modes : Amiga/Blitz
  120. Syntax: FNSOutput bitmap#[,clip_update]
  121.  
  122.   This command selects a bitmap for use by the FNS routines, the bitmap
  123.   must be a previously reserved Blitz 2 bitmap object.  After this
  124.   command all FNS font printing will occur on the selected bitmap.  The
  125.   optional parameter allows you to update the clipping rectangle for
  126.   output at the same time as setting the output bitmap.  Setting
  127.   clip_update to a non-zero value will cause the clipping area to
  128.   automatically be set to the dimensions of the selected bitmap.
  129.  
  130.   NOTE:
  131.   -----
  132.   This command MUST be used before you attempt to use FNSPrint.
  133.   The maximum depth of the bitmap for printing is 8 bitplanes since this
  134.   is all Blitz 2 currently supports.
  135.  
  136.   See: FNSClip, FNSClipOutput.
  137.  
  138. Statement: FNSInk
  139. ------------------------------------------------------------------------
  140. Modes : Amiga/Blitz
  141. Syntax: FNSInk colour#
  142.  
  143.   This sets the output colour for the FNS font drawing routines.  The
  144.       number range is dependant on the depth of the destination bitmap, the
  145.   max posible range, though, is limited to 0 to 255 colours.  The FNS
  146.   output routines will attempt to draw in all the bitplanes of the
  147.   selected bitmap, any extra bits in the ink colour will be ignored.
  148.  
  149.   See: FNSPrefs
  150.  
  151. Statement: FNSPrefs
  152. ------------------------------------------------------------------------
  153. Modes : Amiga/Blitz
  154. Syntax: FNSInk preferences[,colour#]
  155.  
  156.   This sets the output prefs for the FNS font drawing routines but at
  157.   the same time also sets the colour for the FNS routines (optional).
  158.   At the moment the following options are available, the bits of the
  159.   preferences byte are used to select the different options:
  160.  
  161.                             bit 0: Centred text
  162.                             bit 1: Bold text
  163.                 bit 2: Underline
  164.                 bit 3: Right aligned
  165.  
  166.   See: FNSInk, FNSPrint and FNSLength
  167.  
  168. Function: FNSHeight
  169. ------------------------------------------------------------------------
  170. Modes : Amiga/Blitz
  171. Syntax: height.w=FNSHeight(font_num)
  172.  
  173.   This routine returns the height of a previously installed FNS font.
  174.   Font_num should be >=0 and <=15.
  175.  
  176.   See: FNSUnderline and FNSWidth
  177.  
  178. Function: FNSUnderline
  179. ------------------------------------------------------------------------
  180. Modes : Amiga/Blitz
  181. Syntax: under_pos=FNSUnderline(font_num)
  182.  
  183.   This routine returns the underline position of the selected FNS font.
  184.   Font_num should be >=0 and <=15.
  185.  
  186.   See: FNSHeight and FNSWidth
  187.  
  188. Function: FNSWidth
  189. ------------------------------------------------------------------------
  190. Modes : Amiga/Blitz
  191. Syntax: width.w=FNSWidth(font_num)
  192.  
  193.   This routine returns the width in multiples of 16 of the selected FNS
  194.   font.  Font_num should be >=0 and <=15.
  195.  
  196.   See: FNSHeight and FNSUnderline
  197.  
  198. Statement: FNSClip
  199. ------------------------------------------------------------------------
  200. Modes : Amiga/Blitz
  201. Syntax: FNSClip x1,y1,x2,y2
  202.  
  203.   This command is used to limit the output of the FNSPrint command.  The
  204.   co-ordinates given should describe a rectangle that is to be used to
  205.   clip the output.  This rectangle can be thought of as a window on the
  206.   bitmap - no printing can occur outside of the window.
  207.   X1,Y1 are the top left corner of the clipping rectangle and X2,Y2 are the
  208.   bottom right corner.  Please note that both X co-ordinates should be
  209.   multiples of 16 and that X2 should be the heightest multiple of 16 that
  210.   you do not wish output to occur at.  Thus if your bitmap is 320x256 then
  211.   you would use the following to set the clipping rectangle to the full
  212.   bitmap:
  213.         FNSClip 0,0,320,256
  214.  
  215.   See: FNSClipOutput and FNSOutput
  216.  
  217. Statement: FNSClipOutput
  218. ------------------------------------------------------------------------
  219. Modes : Amiga/Blitz
  220. Syntax: FNSClipOutput
  221.  
  222.   This command is used to quickly set the clipping rectangle for the FNS
  223.   commands to the full size of a bitmap.
  224.  
  225.   See: FNSClip and FNSOutput
  226.  
  227. Statement: FNSOrigin
  228. ------------------------------------------------------------------------
  229. Modes : Amiga/Blitz
  230. Syntax: FNSOrigin [x,y]
  231.  
  232.   This command is used to set an origin co-ordinate for printing output.
  233.   Whenever you use FNSPrint, the origin co-ordinates are added (as words)
  234.   to the co-ordinates you give for output.  I.e. setting the origin at
  235.   100,0 and printing at co-ordinates 0,0 will cause the output to be at
  236.   100,0.
  237.  
  238.   Using this command without any parameters will cause the origin to
  239.   be reset to the position 0,0.
  240.   Note: This command does not affect the use of the FNSClip command.
  241.  
  242. Function: FNSLength
  243. ------------------------------------------------------------------------
  244. Modes : Amiga/Blitz
  245. Syntax: a=FNSLength (font#,a$/string_address[,prefs])
  246.  
  247.   This command is equivalent of the basic command a=len(a$) except that
  248.   it returns the x size, in pixels, of the string if it were to be printed
  249.   in the font font#.  The optional preferences parameter allows you to
  250.   adjust the output of the string, if you specify no preferences then this
  251.   function will use the previously selected preferences to calculate the
  252.   string length.  Using preferences allows you to account for things like
  253.   bold text output.
  254.  
  255.   See: FNSPrefs
  256.   
  257. Function: FNSVersion
  258. ------------------------------------------------------------------------
  259. Modes : Amiga/Blitz
  260. Syntax: a.q=FNSVersion
  261.  
  262.   This command allows you to test the version number of the FNS library
  263.   that your program is being compiled with.  It returns a quick float value
  264.   and so you should use a quick float variable for the answer.  This doc
  265.   file was written for version 0.992 of the library.
  266.  
  267. Statement: FNSSetTab
  268. ------------------------------------------------------------------------
  269. Modes : Amiga/Blitz
  270. Syntax: FNSSetTab tab_width
  271.  
  272.   Use this command to set the tab spacing used when printing.  The value
  273. given should be the spacing IN pixels.
  274.  
  275.  
  276. Function: FNSLoad
  277. ------------------------------------------------------------------------
  278. Modes : Amiga/Blitz
  279. Syntax: suc=FNSLoad (filename$,font#)
  280.  
  281.   This command is used to load a font from disk and automatically install
  282.   it for use by the FNS commands.  Filename$ should be the full name of the
  283.   file to load (path$+file$) and font# should be 0<= and >=15.  This command
  284.   returns a value of -1 for failure or the font number the font was installed
  285.   as (see InstallFNS).  A failure could either be a load error or an
  286.   installation error.
  287.   You should make sure that the file you load IS an FNS font file.
  288.  
  289.   IMPORTANT NOTE: to use this command, you must have our FUNC library
  290.   installed on your copy of Blitz2.  Running it without this library could,
  291.   and probably will, cause a major crash of your computer.
  292.   Also note that if you do an ERASEALL (this is a FUNC library command for
  293.   erasing banks), you will DELETE your font from memory!
  294.  
  295.  
  296. Statement: FNSUnLoad
  297. ------------------------------------------------------------------------
  298. Modes : Amiga/Blitz
  299. Syntax: FNSUnLoad font#
  300.  
  301.   This command is used to remove a font installed with the FNSLoad command.
  302.   When this command runs it automatically removes the font entry in the FNS
  303.   commands and deletes the memory that the font file is held in.  There is
  304.   no need to do this at the end of a program as the FUNC library
  305.   automatically frees up all allocated memory.
  306.  
  307.  
  308.  
  309. FNS Font file format:
  310. =====================
  311.  
  312.     Header: 256 bytes.
  313.         0-3   : 'FNS.' - file identifier - looked for by InstallFNS
  314.         4-5   : height of font (#word)
  315.         6-7   : width of font in multiples of 16 (#word)
  316.         8-9   : underline position (offset from top of font, #word)
  317.         10-11 : size of data for each font character
  318.             [ (WIDTH/8) * height ]
  319.         32-255: byte giving widths of each character in the font.
  320.             These bytes doesn't really hold the width, rather
  321.             they hold the value to add to the X position of the
  322.             character to get to the position to print the next
  323.             character at (!).
  324.  
  325.         256-EOF:character data starting at ASCII 32 (space)
  326.         
  327. >> END
  328.